Workshop User's Guide 
3.0 Release Notes 



These release notes reflect changes and additions to 
the Lisa Workshop Environment 3.0 release software. 

The notes update the the following chapters: Chapter 
2, The File Manager; Chapter 4, The Editor; Chapter 
5„ The Pascal Compiler; Chapter 6, The Assembler; 
Chapter 7, The Linker; Chapter 8, The Debugger; arid 
Appendix D, Common Problems. Please look over 
the notes and place them with the corresponding 
chapters in your binder for easy reference. 
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Chapter 2 
The File Manager 

overview of Changes to tne File Manager 

The significant changes to the File Manager involve: 

• The operating System's new hierarchical catalog structure. 

• Transfer operations onto more than one micro diskette. 

• Password protection. 

• The new OS device names. 

The Operating System uses new physical device names, but still supports the 
old names as device aliases, you can specify a device using either the name 
or the alias; the OS refers to devices by name. The table shows new names. 

Device Names and Phases 



Name 


Alias 


Device 


#10*1 


RS232A 


Serial Port A 


#10#2 


RS232B 


serial Port B 


#11 


PARAPORT 


Parallel Connector (Lisa 1) 


#12 


UPPER or PARAPORT 


Built-in hard disk (Lisa 2) 


#13 


LOWER 


Micro diskette drive 


#15#1 


ALTCONSOLE 


Alternate console 


#15#2 


MAINCONSOLE 


Main console 


#X 


SLOTX 


Peripheral at expansion slot x 


#x#y 


SLOTxCHANy 


Peripheral at expansion slot x, connector y 


#X#y#2 SLOTxCHANyDEVZ 


Peripheral at expansion slot x, connector 






y, device z 



AddCatalog Command 

Files on a volume can now be arranged under catalogs and subcatalogs. The 
AddCatalog command lets you create new catalogs. The pathname you specify 
for a catalog should refer to a volume that has been initialized using the 
Release 3.0 software 

The hyphen is the catalog delimiter, so a file name referring to a file in a 
catalog might look like -vol-cat-file or -vol-catl-cat2-file, and so on. A file 
name of the form cat-file is interpreted relative to the current prefix and thus 
might refer to -vol-cat-file or -voi-catl-cat-file, depending on whether the 
prefix is set to a volume or to a catalog. A catalog specified by a pathname 
without a volume part will be created using the current main prefix 

There is no special command to put a file in a catalog, once a catalog has 
been created, new files get put into it in two ways: 
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• If the new file's name is specified by a full pathname with volume and 
catalog parts, the file is put in the specified catalog. (A catalog must exist 
before a file can be put into it) 

• If the new file's name is a partial pathname without a volume part and the 
current prefix is a catalog, the file is put in the prefix catalog (or a 
subcatalog, if the file's pathname includes a catalog part)i 

When the OS tries to find a file given a partial pathname, the file will be 
found only if (l) the pathname has no catalog part and is located in the prefix 
volume or catalog, or (2) the pathname has a catalog part corresponding to a 
path starting with a catalog at the top level of the prefix volume or catalog. 

Backup/Copy/Transfer to Multiple Micro Diskettes 
(see sections 25.1, 232, and 23.7) 

The Backup, Copy and Transfer commands now allow backups, copies, and 
transfers to multiple volumes. If a list of files is being copied (or backed up, 
or transferred) to a micro diskette and you run out of space, you will be told 
which file dldnt fit and how many more blocks were needed, and you win be 
asked whether you want to continue on another diskette. If you answer Yes, 
you will be led through a diskette change and the operation will continue. 
Note that the volume names of the subsequent diskettes need not match the 
first even if the original destination was specified with a particular volume 
name (instead of a device name). 

List and Names Commands (See Sections 23u4 and 23.15) 

There are two new attributes for items in the List display. The D attribute 
indicates a directory (a catalog object) and the * attribute indicates a 
password-protected file (see Password Protection, below). 

The List and Names commands now indent names to show the catalog structure 
whenever you list a contiguous set of files. If you specify a wildcard character 
followed by a string to match, the files shown will not necessarily be 
contiguous, and will not be indented. 

When a file name has to be truncated to fit into a limited field of the display 
(as in the List command), the missing characters are now indicated by an 
ellipsis (...X 

Prefix Command (See Section 23S) 

prefixes may now be set to catalogs in addition to volumes. A prefix to a 
catalog or subcatalog must be specified with a complete pathname. 

The effect of the current prefix on the interpretation of file names is discussed 
under AddCatalog Command, above. 
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WARNING 

Setting the main prefix (or working directory) may cause problems when 
running programs that use intrinsic units (this includes all the Workshop 
tools). The OS loader tries to find a program's intrinsic libraries using the 
pathnames it finds in INTRINSIC.LIB; if these names are partial 
pathnames, it looks on the prefix volume or catalog, not the boot volume 
To assure that your program's intrinsic libraries are found, you can do one 
of two things: 

• Copy the intrinsic libraries to the prefix catalog. This way, you can 
support several different library environments on the same volume, 
though you could end up with a proliferation of library files. 

• Change the names of the libraries in INTRINSIC.LIB to pathnames of 
the form -#BOOT-libname (using the lUManager, described in Chapter 
11, utilities), then reboot so the OS will store the new names. This 
method is better, but be careful about changing things in 
1NTRINSIC.LIB. 



If you unmount the main prefix volume by ejecting the diskette, Scavenging the 
volume, or using the unmount command, the boot volume becomes the prefix 
volume. 

Rename Command (See Section 23.6) 

To rename a file to a name that only differs from the original in the case of 
the letters (e.g., DEMOGRAPHICS.OBJ to DemoGraphics.Obj), you must first 
Rename the file to a temporary name, then Rename that to the name you want 

Password Protection (See Section 25.10, FileAttributes) 

Two new commands for password protection are found under the FileAttributes 
command. AddPassword allows you to password-protect a file (or files, using 
wildcards^ RemovePassword allows you to remove a file's password, but you 
must know the password to remove it 

The Workshop tools can't open a file once it is password-protected; you must 
remove the password before you can use the file. 

initialize Command (See Section 23,11 and 2A1) 

volumes initialized under the new workshop and OS have a hierarchical catalog 
structure. Since this structure cannot be applied retroactively, an existing 
volume must be reinitialized in order to take advantage of these features. 
Commands that operate on a list of files (e.g, List) run much faster on a 
reinitialized disk, because in the new structure names are already sorted. 
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Online command (See Section 23.14) 

The Online command now displays both the new OS device names and the old 
names, which are now device aliases. The new device names are listed in the 
Overview at the beginning of this section, and shown in the syntax diagrams 
under File Specifiers, below. 

The prefix attribute P is now sometimes displayed as a lowercase p. Uppercase 
P indicates that the main prefix is the indicated volume, while lowercase p 
indicates that the prefix is a catalog on that volume. 

NOTE 

The Online command uses the configuration information set by 
Preferences. If Online output says that it could not find #11 (PARAPORT) 
on a Lisa 2/10, use Preferences to detach the nonexistent device. If the 
Workshop pauses unexpectedly in the middle of Online output, it means a 
device is configured but not present Make sure that Preferences' idea of 
how the system is configured is correct 

File specifiers (See Section 2A2) 

File specifiers have changed to allow for subcatalogs, new device names, and the new 
wild card characters. The diagrams that follow show the new format of file 
specifiers, replacing those on pages 2-9 and 2-10 of the manual. (The logical device 
names have not changed, but the diagram is repeated here for convenience.) A full 
pathname must not exceed 255 characters; the pieces between dashes (-) must not 
exceed 32 characters. 



file-specifier 



W 



file-name-or-pattern 



T~+ 



logical-device 



file-name-or-pattern 



T. 



volume/catalog-spec 



S \ » | file-name { j — ► 

* ^-* wild-card-spec — J 



volume/catalog-spec 
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physical-device 



u 



physical-device-name 



physical-device-alias 



rr 



physical- device-name 



> 



^ — » C ***v ) — ' 

y "— > C *x*y*z ) — ' 

^—» ( #10*2 ) — ' 

^— » { #15*2 V ^ 



physical-device-alias 



*■—»( UPPER 



^— » ( lower" 



v — ►( SLOTx" 



> 



^-» ( SLOTxCHANy """V ^ 
**-* £ SLOTxCHftNyDEVz"^) --' 
"*— > ( RS232ft 



V 



*■*-» ( RS232B~ 



s — » ( ftLTCONSOLE 
^— •>( MAINCONSQLE 



fT/w device names on the left correspond to the device aliases on the right.) 
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logical -device 



► (console y 

""-» ( PRINTER y ^ 

^— > C keyboard} - 



wild-card-spec 
■—<; 



inn-1 — -^ 



T 



string- 1 



•0- 



^ — ► strina-2 — ^ 



New * and £ Wildcard Characters (See Section 23) 

Because of the new hierarchical catalog structure, the meanings of the - and ? 
wildcard characters have changed, and the new analogous wildcards * 
(OPTION -) and I (OPTION ?) have been added. The plain - and ? wildcards 
mean search for a match only across the top level of the catalog, while the 
option wildcards mean search through all levels. The way in which the matches 
are made is the same: 

- matches any string in the top level of the catalog. 

* matches any string throughout all levels of the catalog. 

? matches any string in the top level of th£ catalog, asking for confirmation 
of each file name before performing the operation. 

I matches any string throughout ail levels of the catalog, asking for 
confirmation of each file name before performing the operation. 
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Chapter 4 
The Editor 

stationery (See Section 423) 

If you want to use stationery on a volume other than your boot volume, type in 
the volume name after you choose Tear Off Stationery. 

Note that the file name "PAPER.TEXT" is reserved for the default stationery 
template and should not be used for other purposes. 

Editing Multiple Files (See Section 42A) 

If the Editor becomes sluggish when you have many documents open at the 
same time (or a few large documents), put some of them away, and then 
continue. 

Using the Arrow Keys to Move the Insertion Point (See Section 43.1) 

You can now use the arrow keys on the numeric keypad to move the insertion 
point The arrow keys are the ♦,*,/, and , keys with the black triangle in a 
box on them, as shown below. Pressing an arrow key moves the Insertion point 
one position in the direction of the arrow—either one character to the right or 
left, or one line up or down. If the insertion point is at the beginning of a 
line, the left arrow will move it to the end of the previous line; the right arrow 
will move it from the end of a line to the beginning of the next line. 

You can also use the m key in combination with the arrow keys to move the 
insertion point farther. Holding down the « key and pressing the left or right 
arrow will move the insertion point to the beginning or end of the line, 
respectively. Holding down the « key and pressing the up or down arrow will 
move the insertion point to the beginning or end of the document, scrolling the 
window if necessary to display it 



1 

} 

: 

i 


! 
1 

{ 


*l 


* 

LfJ 



The Arrow Keys 
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Selecting the Last Line of a Document (see Section 433) 

A triple-click will not select the last line of a document unless the line ends 
with a carriage return. 

Windows Menu 

The Windows menu lets you keep track of the windows you have open. It lists 
the names of all open windows, with a check mark indicating which is the 
active window. To make a different window active and bring it to the top, 
choose that window's name from the menu. An example of the windows menu 
is shown. 



U/indows 



-#12-MyProg.TEXT 
- lower -memo.TEXT 
VUntitled-03 



Markers Menu 

The Markers menu lets you associate a name with a specific place in a 
document, and easily find that place again later. 

To set a marker: 

L Select the portion of text that you want marked. This can be an 
insertion point, or any selection of text 

2. Choose Set Marker Named ? from the Markers menu. 

3. Type the name you want the marker to have. Marker names can consist 
of any characters, including spaces, up to 20 characters. 

4. Type [RETURN). 

Nothing in your document will be changed, but the marker name will appear in 
the Markers menu. When you choose the marker name from the menu, the 
window will scroll so that the point or selection of text associated with that 
marker is visible. You can set up to 18 markers in a document 

Whenever you have at least one marker set, there is a Delete Marker Named ? 
item in the Markers menu This allows you to delete any of the markers you 
have set, when you dont need them anymore. 

72? delete a marker: 

L Choose Delete Marker Named ? from the Markers menu. 

2. Type the name of the marker you want deleted. 
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3. Type [RETURN]. 

The marker name will be removed from the Markers menu. 

The items in the Markers menu are associated with a particular document so 
the menu will change when you move between documents, out the markers you 
set will stay associated with each document until you delete them (even when 
you leave the Editor or the Workshop). An example of the Markers menu is 
shown. 



Markers 



Set Marker ... #M 
Delete Marker ... 



main program 

sort procedure 
i? 



end 



File Menu (See section 45) 

The following commands have been added to the File menu: 

Throw Away Window 

Discards the active window. If you have made any changes to the document 
the Editor asks if you really want to discard the window. If you have 
previously saved the document the copy on disk remains; only the contents of 
the window are discarded. 



Eject Diskette 

Ejects the micro diskette, 
typing E. 



You can also eject by holding down the « key and 



Search Menu (See Section 4.7) 

The following changes have been made to the Search menu, as shown on the 
next page. Note that the options determining how the search is to be done 
(whether case is important etc.) are no longer marked with a check mark. 
Instead, only the options currently in effect are shown; to switch between the 
two options in each set choose the menu item. 
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Search 



Find ... itF 

Find Same lis 

Find Contents of Clipboard 



Find & Paste fill 



Search is Tokenized 
Search is Not Case Sensitive 
Search is Not IfFaparound 



Go To Line # *& 

Shew Current Insertion Point 



Find Contents of Clipboard 

Search for the contents of the Clipboard, if the Clipboard contains more than 
one line, the Editor looks for only the first line. 

Search is Tokenized/Search is Literal 

If Search is Tokenized appears in the menu, the Editor looks for the search 
string as a separate word. If Search is Literal appears, the Editor looks for any 
occurrence of the search string, even if it appears in the middle of another 
word. To toggle between the two options, choose the menu item. (The Search 
is Tokenized/Search is Literal choice replaces the Separate Identifiers and All 
Occurrences menu items.) The definition of a word here is any combination of 
alphanumeric characters, dollar signs, and underoars, bounded by spaces, 
punctuation, or other symbols. 

Search is Case Sensitive/Search is Not Case Sensitive 

If Search is Case Sensitive appears in the menu, the Editor looks for the search 
string with the case of the letters exactly as you typed it If Search is Not 
Case Sensitive appears, the Editor looks for any occurrence of the search 
string, regardless of case. To toggle between the two options, choose the menu 
item. (The Search is Case Sensitive/Search is Not Case Sensitive choice 
replaces the Cases Must Agree and Cases Need not Agree menu items.) 
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Search is Wraparound/Search is Not wraparound 

A search is always done starting at the insertion point If Search is 
wraparound appears in the menu,, the Editor searches from the insertion point 
to the end of the document then starts at the beginning of the document, and 
searches to the insertion point If Search is Not Wraparound appears, the 
Editor only searches from the insertion point to the end of the document To 
toggle between the two options, choose the menu item. 

Go To Line* 

The Go To Line # command lets you scroll the window to show text starting at 
a particular line number in a document The Editor asks you what line you 
want to go to. If you specify a line number greater than the number of lines 
in the document, you will get a message to that effect The Go To Line # 
command can also be executed by holding down the m key and typing G. 

Show Current insertion Point 

Choosing Show Current Insertion Point scrolls the window to where the 
insertion point is. If the insertion point is already in the window when you 
choose Show Current Insertion Point, the command does nothing. 

Type Style Menu (See Section *A) 

The Type Style menu has been changed so that you can choose separately the 
size of the type in which a document is displayed, and whether the type style 
is modem or classic The classic type fonts have serifs; the modem fonts do 
not The new Type style menu is shown below. 



Type Style | 


■/Modern 


Classic 


8 Point 20 Pitch 


8 Point 15 Pitch 


V10 Point 


12 Point 


12 Point PS 
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Print Menu (9ee section 4$) 

The Plain Keywords and Differentiated Keywords items are no longer on the 
Print menu. Keywords are always printed as plain text 

Editor initialization Errors 

If the initialization of the Editor fails due to lack of disk space (Error 309), and 
space on the disk is then made free,, the next attempt to start the Editor will 
also fail (Error 304). You must enter the ManageProcess subsystem of the 
System Manager, Kill the Editor process, and then try again 

Text Files 

The Editor, language processors, and other Workshop utilities expect a standard 
.TEXT file as input The internal structure of a text file in a block-structured 
device is described in the Pascal Reference Manual: 

• Each page (two 512-byte blocks) contains some number of complete lines 
of text and Is padded with null characters (ascii o) after the last line as 
necessary to complete the page. 

• Two 512-byte header blocks are also present at the beginning of the file. 
These may or may not contain information. 

• A sequence of leading spaces (ASCII 32 decimal, $20 hexadecimal) can be 
compressed into a 2-byte code namely, a DLE character (ASCII 16 
decimal, $10 hexadecimal), followed by a byte containing the value 32 
decimal plus the number of spaces represented. 

Maximum Length of Lines 

The Editor now has a maximum line length of 255 characters. You'll get an 
error message if you create a line of more than 255 characters, or a warning if 
you read in a file containing a line of more than 255 characters. (This change 
is unlikely to affect you, since even using the smallest type font, you can't 
display more than about 150 characters in a line.) 
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Chapters 
The Pascal Compiler 



New Compiler Commands (See Section 5.3) 

Five new Compiler commands have been added: $ASM, $E, $M, $P, and $U. 
$ASM controls whether or not the listing shows the assembly code generated 
by your Pascal statements. $E lets you automatically invoke the Editor. $M 
lets you generate Macintosh code. $P starts a new page in your listing. $U 
controls the Compiler's search for a regular or intrinsic unit's interface. 

For a detailed update, consult the 3.0 Release Notes for Chapter 12, The 
Compiler, of the Pascal Reference Manual for the Lisa 
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Chapter 6 
The Assembler 



.MAIN Assembler Directive (See Section 6.5) 

The Assembler now has a .MAIN directive, which allows you to generate a 
main program: 

.MAIN ProgName ; begin main program 
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Chapter 7 
The Linker 



New Linker Options (See Section 7.3) 

The Linker accepts the following new options: 

+C moduleName segmentName 

Make a copy of moduleName in segmentName. Used for 
performance reasons to prevent cross-segment calls and the possible 
need for a segment swap. 

+F Means the link is a link of system code that runs in Domain 0, and 
therefore cannot use MMU's 1-16. The default is -F. 

+1 Include interfaces in an intrinsic library link. The default is +1. 
(Note: this is a change — in previous releases, interfaces were not 
included.) 

♦O Emit OS data record for main programs. Used by the OS for initial 
program loading. The default is +0. 

+X Mac link — generate an object file specially designed for the 
Macintosh Resource Compiler. The default is -X. 

*Z Warn if codesize is too large. The default is +Z. 

The -H and +S options (for setting initial disk space and stack size) no 
longer have any effect. 

Intrinsic Units (See Section 7.5) 

You can now link to intrinsic units you've created yourself; you are no longer 
limited to those provided by Apple. For information on writing intrinsic 
units, see the Release 3.0 Notes to the Pascal Reference Manual, Chapter 9, 
Units. 
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Chapter 8 
The Debugger 



Changes In Printing Commands (See section 8A9.4) 

The Debugger now supports both parallel and serial printers. The PR command 
has been extended to let you enable a printer attached to any of the parallel or 
serial connectors. Its new format is: 

PR n m 

where n and m indicate which connector your printer is on (or which printer to 
enable): 

n - Disable printer,, or no printer on system, 

n - 12, or 3 Expansion slot 1, 2, or 3, respectively, 

n - 4 Serial connector A. 

n - 5 Serial connector B. 

If n is 1, 2, or 3, the second parameter indicates which connector the printer is 
on: 

m - 1 Lower connector, 

m - 2 Upper connector. 

The PB command replaces the PU and PL commands to generate bug reports: 

PBnm 

where n and m are the same as above. 
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D.7 Installation Problems 

1. The most common Installation problems are caused by not following the 
installation instructions To get the correct versions of all the software 
onto your disk, including hooting information, you must go through the 
installation procedure in Chapter 1 of the manual. Other methods, such 
as using your old version of the File Manager to copy the files, will 
cause problems. 

2. If you are installing the 3.0 Workshop over an older version of the 
Workshop, and you do not install the optional tools from diskettes 6 
through 9 (see Section D.8, below), the older versions of the tools will 
still be on your hard disk. These do not work on the 3.0 Workshop and 
take up needless disk space. Consult the list of 3.0 files (in the Pascal 
Reference Manual Appendix I, Pascal Workshop Files) and use the File 
Manager's Delete command to delete all files on the list that are still on 
your disk but were not just installed with the 3.0 Workshop. A better 
way to avoid this problem is to save any personal files you need onto 
diskettes, then reinitialize the disk, reinstall the Office System if 
desired, and install the 3.0 Workshop. 

3. The 3.0 workshop will not work on the same disk as pre-3.0 versions of 
the Office System. Use separate disks if this arrangement is required. 

4. The first time you start up the Workshop, it may appear to hang. Don't 
worry, this is actually just a long delay—the Workshop anticipates the 
maximum possible number of attached devices (such as hard disks) and 
has to "look" the first time to see which of these devices is really 
attached. This can take as long as four or five minutes. 

D.8 Files Not Automatically installed 

The files on diskettes 6 through 9 of the release 3.0 Workshop are optional 
tools, and are not automatically installed by the Installer program. (These tools 
are programming aids such as Find, SXRef, and Pasmat; filters such as 
LineCount and Translit; and specialized tools such as QuickDraw, QuickPort, 
and Macintosh support tools.) Use the File Manager to copy any of these tools 
that you wish to use frequently onto your hard disk. When you copy them, you 
can shorten some of the file names by eliminating the prefix. For example, to 
eliminate the "MAC/" prefix from all of the Macintosh files, copy 
-LOWER-MAC/- to -. Do not do this for the QD and QP object files; the 
sample programs depend on the names as they are. 

D.9 Programs Compiled on Previous Releases of the Workshop 



Notes D-l 



Workshop 3.0 Notes Common Problems 



Programs created on an earlier release of the Workshop will not work on the 
3.0 Workshop until you have relinked them using the new Linker and libraries. 
Unless you saved the unlinked object file, you must recompile as well. Old 
Workshop tools will not work on the 3.0 Workshop; use the equivalent new tool 
from the 3.0 release disks. 

Programs developed in the 2.0 Workshop that use QuickDraw graphics need to 
change the list of files to link to: instead of linking to iOSPasLib and 
<QD/QDStuff (which contains a list of other QuickDraw files), link to 
IOSPasLib, QD/Support, and SyslLib. 

Minor changes have also occurred in the interface to QuickDraw. 
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